Configure any setting from the environment - #357

Closes #182.

The request there was to control the application entirely with environment variables, for automated deployments where the config plane and the data plane are kept apart. Until now every setting had to be in the file.

How it looks

Take the name of the setting, put KEEPASS4WEB_ in front, and step into a section with two underscores:

KEEPASS4WEB_PORT=8080
KEEPASS4WEB_DB_SESSION_TIMEOUT='45 minutes'
KEEPASS4WEB_AUTH_BACKEND=LDAP
KEEPASS4WEB_LDAP__BASE_DN='ou=users,dc=example,dc=org'
KEEPASS4WEB_LDAP__PASSWORD='...'
KEEPASS4WEB_SEARCH__FIELDS='[title, username, url]'

One underscore is part of a name, two are a level, so KEEPASS4WEB_DB_SESSION_TIMEOUT is the top-level setting and KEEPASS4WEB_LDAP__BASE_DN is base_dn inside LDAP. A variable replaces whatever the file said.

The file is now optional. With no config.yml present and no --config, the environment and the defaults are the whole configuration, so an image can ship without one. Asking for a file with --config that is not there is still an error, so a typo in the path cannot quietly start a server on defaults.

Two decisions worth reviewing

Values are text, not YAML. Parsing them as YAML would be the obvious thing, and it is wrong here: a client secret of 12345 would arrive as a number and a password of yes as a boolean, and both would be rejected against a string field. Since secrets are exactly what this feature is for, values are taken literally. That leaves the settings which are not strings — port and the five booleans — and those now accept the text spelling of their value, which is all a variable can offer. Lists are the one exception: '[title, url]' is read as YAML, because there is no other way to write one.

Existing spellings of a section are reused. The shipped file writes LDAP: and OIDC:, which serde reads as the same field as ldap and oidc. Laying a lowercase key beside one of those is read as the field being given twice, and the whole config is rejected with duplicate field ldap. I hit this the moment I tested against the real config.yml, so a section is matched case-insensitively and written back under the spelling already there.

Checked

23 unit tests over the overlay and the loading, covering the nesting rule, sections created on the way down, lists, precedence, an absent file, an empty file, a name with nothing between the separators, and that a numeric or boolean-looking secret survives as text.

Also run for real. With no config.yml in the directory at all:

KEEPASS4WEB_LISTEN=127.0.0.1 KEEPASS4WEB_PORT=8183 KEEPASS4WEB_USE_KEYRING=false \
KEEPASS4WEB_AUTH_BACKEND=None KEEPASS4WEB_FILESYSTEM__DB_LOCATION=./test.kdbx \
KEEPASS4WEB_DB_SESSION_TIMEOUT='45 minutes' keepass4web-rs

WARN  use_keyring is off: database keys are held in process memory instead of the kernel keyring
INFO  starting service: "actix-web-service-127.0.0.1:8183", listening on: 127.0.0.1:8183

— a string, an integer and a boolean all arriving from the environment. And with a file present that says port: 8080 and LDAP: { uri: 'ldap://from-file:389' }, KEEPASS4WEB_PORT=8184 and KEEPASS4WEB_LDAP__URI both win, with no duplicate-field error.

config.example.yml and the README describe the scheme. No existing setting or default changed, and --config behaves as before when a path is passed.

Summary by CodeRabbit

• New Features

  • Added support for configuring settings through KEEPASS4WEB_ environment variables, including nested values, lists, and scalar settings.
  • Environment variables override values from configuration files.
  • Configuration files are now optional, allowing fileless deployment.
  • The configuration file path can be explicitly selected through the command-line option.

• Bug Fixes

  • Improved configuration error messages for missing, unreadable, or invalid explicitly selected files.
  • Empty and missing default configuration files are handled gracefully.

• Documentation

  • Expanded configuration and Docker Compose deployment documentation, including environment-variable examples and precedence rules.